orixfandomcom-20200214-history
ORIX Commands
All ORIX Core Messages (Required and Optional) are structured as in the following examples: *announce:{"name":"ACS Remote Control","alert":1} *say:Hello! My name is Fred. *menu:{"operator":"fc76e4a6-c76b-41d5-9c76-dc0ae28d9c0d","menu":"remotemain"} *stand: *The first character is *, indicating an ORIX Device-to-Core message *Following that is the command name, such as "announce:", which MUST end in a colon. *Following that is one of the following: **A set of arguments specified in a JSON format, or **A single string argument, or **Nothing (if the command needs no arguments) All ORIX Cores must listen for ORIX Core messages on channel -15180924. (Optionally, it may also listen for messages on channel 9360. If so, messages received on either channel should be treated identically.) Messages received on this channel that do not fit the structure of an ORIX command, or which contain a command the Core does not recognize, should be ignored. Commands the Core recognizes, but that contain improper or invalid argument values, or that omit required arguments, may be handled in any way the Core chooses. It may ignore them, it may return an error message to the sending device, or it may have a different effect (e.g. causing the robot to speak an error message). Commands the Core recognizes, that contain enough valid arguments to allow it to execute the command, but also contain additional arguments that the Core does not recognize, should be executed ignoring the unrecognized arguments. This allows a device to send a Core message that takes advantage of a feature some Cores possess, while still allowing a Core that does not have that feature to respond to the message in whatever way it can. Universal Parameters Any of the following parameters may be used with any Core Command unless otherwise specified: method: Specifies what is causing the requested effect. The following values are recognized: *'direct': Represents an instruction being sent directly to the Core from a device installed in the unit, like an access panel. Usually does not require any password or login. If specified in a command from a device that is not attached to the avatar, the entire command is ignored and an error may be sent to the sending device. *'wired': Represents an instruction being sent to the Core from a remote device that is physically connected to the unit, like a maintenance station or charger. May require a password or login. The Core may (but need not) attempt to verify the validity of the physical connection, for example by asking the unit if the device is connected, or by checking the sending device's distance from the unit. *'wireless': Represents an instruction being sent to the Core from a remote device that is making use of an authorized non-physical connection to the unit, like a remote control. May require a password or login. The Core may (but need not) reject such commands if, for example, it does not have an active wireless interface. *'splice': Represents an instruction being sent to the Core from a device that has spliced itself into the unit's system without using a designed-in interface, like a sonic screwdriver or other tool. It can also represent electrical interference with the unit's operation. This generally represents an attempt to circumvent security systems or to do things the Core is not designed to allow, although it isn't necessarily unauthorized - for example, installing a new access panel might involve commands using the "splice" method. The Core may require an active effort to work around a security system before permitting a splice. *'physical': Represents a brute-force physical effect that affects the unit's actions, like a hand manipulating the unit's body or a force ray breaking connections within the unit. Physical effects avoid most security systems, but some may be overcome by the unit's own strength. Many physical effects can work only if the unit is partly or fully disabled. A physical connection is usually permitted, but the Core may reject any command if the unit is able to resist the physical manipulation and chooses to do so. *'debug': Represents a command being sent for purposes of debugging the Core. A Core may refuse such commands for any reason, but may accept them from certain individuals or under certain circumstances to help troubleshoot. operator: '''If provided, specifies the key (UUID) of the individual operating the device sending the command. '''login: '''When the *login: command is used, it returns a login code that the logged-in device should include with future commands to verify that it is logged in. See the login: command for more details. If the login parameter is specified, it should '''only be sent directly to the Core to be commanded, using llRegionSayTo, to prevent eavesdropping. waitbefore: '''If a numeric value is provided, the Core should wait that many seconds before executing the command. It may do other things during the delay. The number should be relatively small; long delays should use a timer instead. '''waitafter: '''If a numeric value is provided, the Core should wait that many seconds after executing the command before going on to the next. It may do other things during the delay. The number should be relatively small; long delays should use a timer instead. '''echo: If provided, the value of the parameter is sent back to the sending device after the Core has finished processing the command and waited for any waitafter pause. This can allow the Device to keep less state as it may rely on the Core to remind it what it should do next. Required ORIX Core Messages Every ORIX Core must recognize and respond to the following commands: * * * * * * * * Optional ORIX Core Messages A Core that only responded to the required messages would be a very dull core indeed. However, no two Cores will offer exactly the same features. Each Core will recognize the messages that are useful for the features it implements, and ignore the others. It is strongly recommended that if a Core is capable of doing what a particular message requests, it should do so. For example, if your Core has the ability to be turned on and off (as most Cores probably do), it should respond to *power:1 by turning on, and to *power:0 by turning off. This will allow for the maximum compatibility with other devices that may be capable of instructing a Core to power on or off. However, it is entirely acceptable for your Core to ignore those messages if it does not have the ability to be turned on and off, or to return an error message if the necessary conditions for being turned on or off are not met (e.g. needing to be logged in). The following ORIX Core Messages are available: Custom Core Messages Each Core will have unique features and ways of doing things that may not be compatible with existing ORIX messages, and that is entirely acceptable. The goal is to allow devices to be able to work together when it makes sense for them to do so, not to impose constraints on designers' creativity. To that end, any ORIX Core builder may invent new messages, or new parameters for existing messages, to supplement the ORIX Core Messages. If you like, you may document these messages here on this wiki so that others can make devices that take advantage of those features. (It is recommended that you do this early in the design of the product, as JulieDoll or others might have helpful suggestions to make your messages easier for others to use and therefore more likely to be used.) Alternatively, you may leave them undocumented, with the intention of only having them used in your own products. Do not add any parameters whose name begins with an underscore ("_"). Such names are reserved for internal use by cores. For example, a core might add a parameter to a message to share the key of the sending device with other scripts.